home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tcl / splitlist.z / splitlist
Encoding:
Text File  |  1998-10-30  |  12.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))                                        TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement -
  10.      manipulate Tcl lists
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  14.  
  15.      int
  16.      TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt(_i_n_t_e_r_p, _l_i_s_t, _a_r_g_c_P_t_r, _a_r_g_v_P_t_r)
  17.  
  18.      char *
  19.      TTTTccccllll____MMMMeeeerrrrggggeeee(_a_r_g_c, _a_r_g_v)
  20.  
  21.      int
  22.      TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt(_s_r_c, _f_l_a_g_s_P_t_r)
  23.  
  24.      int
  25.      TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt(_s_r_c, _d_s_t, _f_l_a_g_s)
  26.  
  27. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  28.      Tcl_Interp   *_i_n_t_e_r_p      (out)     Interpreter to use for error         |
  29.                                          reporting.  If NULL, then no error   |
  30.                                          message is left.
  31.  
  32.      char         *_l_i_s_t        (in)      Pointer to a string with proper list
  33.                                          structure.
  34.  
  35.      int          *_a_r_g_c_P_t_r     (out)     Filled in with number of elements in
  36.                                          _l_i_s_t.
  37.  
  38.      char         ***_a_r_g_v_P_t_r   (out)     *_a_r_g_v_P_t_r will be filled in with the
  39.                                          address of an array of pointers to
  40.                                          the strings that are the extracted
  41.                                          elements of _l_i_s_t.  There will be
  42.                                          *_a_r_g_c_P_t_r valid entries in the array,
  43.                                          followed by a NULL entry.
  44.  
  45.      int          _a_r_g_c         (in)      Number of elements in _a_r_g_v.
  46.  
  47.      char         **_a_r_g_v       (in)      Array of strings to merge together
  48.                                          into a single list.  Each string will
  49.                                          become a separate element of the
  50.                                          list.
  51.  
  52.      char         *_s_r_c         (in)      String that is to become an element
  53.                                          of a list.
  54.  
  55.      int          *_f_l_a_g_s_P_t_r    (in)      Pointer to word to fill in with
  56.                                          information about _s_r_c.  The value of
  57.                                          *_f_l_a_g_s_P_t_r must be passed to
  58.                                          TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))                                        TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74.      char         *_d_s_t         (in)      Place to copy converted list element.
  75.                                          Must contain enough characters to
  76.                                          hold converted string.
  77.  
  78.      int          _f_l_a_g_s        (in)      Information about _s_r_c. Must be value
  79.                                          returned by previous call to
  80.                                          TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt, possibly OR-ed with
  81.                                          TTTTCCCCLLLL____DDDDOOOONNNNTTTT____UUUUSSSSEEEE____BBBBRRRRAAAACCCCEEEESSSS.
  82.  
  83.  
  84. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  85.      These procedures may be used to disassemble and reassemble Tcl lists.
  86.      TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt breaks a list up into its constituent elements, returning
  87.      an array of pointers to the elements using _a_r_g_c_P_t_r and _a_r_g_v_P_t_r.  While
  88.      extracting the arguments, TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt obeys the usual rules for
  89.      backslash substitutions and braces.  The area of memory pointed to by
  90.      *_a_r_g_v_P_t_r is dynamically allocated;  in addition to the array of pointers,
  91.      it also holds copies of all the list elements.  It is the caller's
  92.      responsibility to free up all of this storage.  For example, suppose that
  93.      you have called TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt with the following code:
  94.  
  95.           int argc, code;
  96.           char *string;
  97.           char **argv;
  98.           ...
  99.           code = Tcl_SplitList(interp, string, &argc, &argv);
  100.  
  101.      Then you should eventually free the storage with a call like the
  102.      following:
  103.  
  104.           free((char *) argv);
  105.  
  106.  
  107.      TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt normally returns TTTTCCCCLLLL____OOOOKKKK, which means the list was
  108.      successfully parsed.  If there was a syntax error in _l_i_s_t, then TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR
  109.      is returned and _i_n_t_e_r_p->_r_e_s_u_l_t will point to an error message describing
  110.      the problem (if _i_n_t_e_r_p was not NULL).  If TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR is returned then no  |
  111.      memory is allocated and *_a_r_g_v_P_t_r is not modified.
  112.  
  113.      TTTTccccllll____MMMMeeeerrrrggggeeee is the inverse of TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt:  it takes a collection of
  114.      strings given by _a_r_g_c and _a_r_g_v and generates a result string that has
  115.      proper list structure.  This means that commands like iiiinnnnddddeeeexxxx may be used
  116.      to extract the original elements again.  In addition, if the result of
  117.      TTTTccccllll____MMMMeeeerrrrggggeeee is passed to TTTTccccllll____EEEEvvvvaaaallll, it will be parsed into _a_r_g_c words whose
  118.      values will be the same as the _a_r_g_v strings passed to TTTTccccllll____MMMMeeeerrrrggggeeee.
  119.      TTTTccccllll____MMMMeeeerrrrggggeeee will modify the list elements with braces and/or backslashes in
  120.      order to produce proper Tcl list structure.  The result string is
  121.      dynamically allocated using mmmmaaaalllllllloooocccc(((())));  the caller must eventually release
  122.      the space using ffffrrrreeeeeeee(((()))).
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))                                        TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt((((3333TTTTccccllll))))
  137.  
  138.  
  139.  
  140.      If the result of TTTTccccllll____MMMMeeeerrrrggggeeee is passed to TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt, the elements
  141.      returned by TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt will be identical to those passed into
  142.      TTTTccccllll____MMMMeeeerrrrggggeeee.  However, the converse is not true:  if TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt is
  143.      passed a given string, and the resulting _a_r_g_c and _a_r_g_v are passed to
  144.      TTTTccccllll____MMMMeeeerrrrggggeeee, the resulting string may not be the same as the original
  145.      string passed to TTTTccccllll____SSSSpppplllliiiittttLLLLiiiisssstttt.  This is because TTTTccccllll____MMMMeeeerrrrggggeeee may use
  146.      backslashes and braces differently than the original string.
  147.  
  148.      TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt and TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt are the procedures that do all of
  149.      the real work of TTTTccccllll____MMMMeeeerrrrggggeeee.  TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt scans its _s_r_c argument and
  150.      determines how to use backslashes and braces when converting it to a list
  151.      element.  It returns an overestimate of the number of characters required
  152.      to represent _s_r_c as a list element, and it stores information in
  153.      *_f_l_a_g_s_P_t_r that is needed by TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt.
  154.  
  155.      TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt is a companion procedure to TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt.  It does
  156.      the actual work of converting a string to a list element.  Its _f_l_a_g_s
  157.      argument must be the same as the value returned by TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt.
  158.      TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt writes a proper list element to memory starting at
  159.      *_d_s_t and returns a count of the total number of characters written, which
  160.      will be no more than the result returned by TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt.
  161.      TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt writes out only the actual list element without any
  162.      leading or trailing spaces: it is up to the caller to include spaces
  163.      between adjacent list elements.
  164.  
  165.      TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt uses one of two different approaches to handle the
  166.      special characters in _s_r_c.  Wherever possible, it handles special
  167.      characters by surrounding the string with braces.  This produces clean-
  168.      looking output, but can't be used in some situations, such as when _s_r_c
  169.      contains unmatched braces.  In these situations, TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt
  170.      handles special characters by generating backslash sequences for them.
  171.      The caller may insist on the second approach by OR-ing the flag value
  172.      returned by TTTTccccllll____SSSSccccaaaannnnEEEElllleeeemmmmeeeennnntttt with TTTTCCCCLLLL____DDDDOOOONNNNTTTT____UUUUSSSSEEEE____BBBBRRRRAAAACCCCEEEESSSS.  Although this will
  173.      produce an uglier result, it is useful in some special situations, such
  174.      as when TTTTccccllll____CCCCoooonnnnvvvveeeerrrrttttEEEElllleeeemmmmeeeennnntttt is being used to generate a portion of an
  175.      argument for a Tcl command.  In this case, surrounding _s_r_c with curly
  176.      braces would cause the command not to be parsed correctly.
  177.  
  178.  
  179. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  180.      backslash, convert, element, list, merge, split, strings
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.